---
title: الصفحات
description: مقدمة حول صفحات أسترو.
i18nReady: true
---
import ReadMore from '~/components/ReadMore.astro';
import Since from '~/components/Since.astro'

**الصفحات** هي ملفات موجودة في المجلد الفرعي `src/pages/` لمشروع أسترو الخاص بك. وهي مسؤولة عن معالجة التوجيه (Routing)، وتحميل البيانات، والتخطيط العام للصفحة لكل صفحة في موقعك.

## أنواع الملفات المدعومة للصفحات

يدعم أسترو أنواع الملفات التالية في دليل `src/pages/`:

- [`.astro`](#صفحات-أسترو)
- [`.md`](#صفحات-ماركداونmdx)
- `.mdx` (بشرط تثبيت [MDX Integration](/ar/guides/integrations-guide/mdx/#installation))
- [`.html`](#صفحات-html)
- `.js`/`.ts` (كـ [نقاط نهاية (Endpoints)](/ar/guides/endpoints/))

## التوجيه القائم على الملفات (File-based Routing)

يستخدم أسترو استراتيجية توجيه تسمى **التوجيه القائم على الملفات**. كل ملف في دليل `src/pages/` الخاص بك يصبح نقطة نهاية (endpoint) في موقعك بناءً على مسار الملف.

يمكن لملف واحد أيضًا أن يولد صفحات متعددة باستخدام [التوجيه الديناميكي (Dynamic Routing)](/ar/guides/routing/#dynamic-routes). هذا يسمح لك بإنشاء صفحات حتى لو كان محتواك موجودًا خارج الدليل الخاص `/pages/`، مثل [مجموعات المحتوى ](/ar/guides/content-collections/) أو [نظام إدارة المحتوى (CMS)](/ar/guides/cms/).

<ReadMore>اقرأ المزيد حول [التوجيه في أسترو](/ar/guides/routing/).</ReadMore>

### الربط بين الصفحات

اكتب عناصر [`<a>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) HTML القياسية في صفحات أسترو الخاصة بك للربط بصفحات أخرى على موقعك. استخدم **مسار URL نسبي لنطاقك الأساسي** كرابط، وليس مسار ملف نسبي.

على سبيل المثال، للربط بـ `https://example.com/authors/sonali/` من أي صفحة أخرى على `example.com`:

```astro title="src/pages/index.astro"
اقرأ المزيد <a href="/authors/sonali/">عن سونالي</a>.
```

## صفحات أسترو

تستخدم صفحات أسترو امتداد الملف `.astro` وتدعم نفس الميزات مثل [مكونات أسترو](/ar/basics/astro-components/).

```astro title="src/pages/index.astro"
---
---
<html lang="ar" dir="rtl">
  <head>
    <title>الصفحة الرئيسية</title>
  </head>
  <body>
    <h1>مرحبًا بكم في موقعي!</h1>
  </body>
</html>
```

يجب أن تنتج الصفحة مستند HTML كامل. إذا لم يتم تضمينها صراحةً، ستقوم أسترو تلقائيًا بإضافة تعريف `<!DOCTYPE html>` الضروري ومحتوى `<head>` إلى أي مكون `.astro` موجود داخل `src/pages/` افتراضيًا. يمكنك إلغاء هذا السلوك لكل مكون على حدة بوضعه كصفحة [جزئية (Partial)](#الصفحات-الجزئية).

لتجنب تكرار عناصر HTML نفسها في كل صفحة، يمكنك نقل عناصر `<head>` و `<body>` الشائعة إلى [مكونات التخطيط (Layout Components)](/ar/basics/layouts/) الخاصة بك. يمكنك استخدام العديد من مكونات التخطيط أو القليل منها كما تريد.

```astro title="src/pages/index.astro" /</?MySiteLayout>/ {2}
---
import MySiteLayout from "../layouts/MySiteLayout.astro";
---
<MySiteLayout>
  <p>محتوى صفحتي، مغلف داخل تخطيط!</p>
</MySiteLayout>
```

<ReadMore>اقرأ المزيد حول [مكونات التخطيط](/ar/basics/layouts/) في أسترو.</ReadMore>

## صفحات ماركداون/MDX

أسترو أيضًا يعتبر أي ملفات Markdown (`.md`) داخل `src/pages/` كصفحات في موقعك النهائي. إذا كان لديك [MDX Integration مثبتًا](/ar/guides/integrations-guide/mdx/#installation)، فستعامل ملفات MDX (`.mdx`) بنفس الطريقة.

:::tip
فكر في إنشاء [مجموعات محتوى ](/ar/guides/content-collections/) بدلاً من الصفحات لأدلة ملفات Markdown ذات الصلة التي تشترك في هيكل مماثل، مثل منشورات المدونة أو عناصر المنتج.
:::

يمكن لملفات Markdown استخدام خاصية frontmatter الخاصة `layout` لتحديد [مكون تخطيط (Layout Component)](/ar/basics/layouts/) الذي سيلف محتوى Markdown الخاص بها داخل مستند صفحة `<html>...</html>`.

```md {3}
---
# مثال: src/pages/page.md
layout: ../layouts/MySiteLayout.astro
title: صفحتي المكتوبة بماركداون
---
# العنوان

هذه هي صفحتي، مكتوبة بـ **Markdown.**
```

<ReadMore>اقرأ المزيد حول [Markdown](/ar/guides/markdown-content/) في أسترو.</ReadMore>

## صفحات HTML

يمكن وضع الملفات ذات امتداد الملف `.html` في دليل `src/pages/` واستخدامها مباشرة كصفحات على موقعك. لاحظ أن بعض ميزات أسترو الرئيسية غير مدعومة في [مكونات HTML](/ar/basics/astro-components/#مكوّنات-html).

## صفحة خطأ 404 مخصصة

لصفحة خطأ 404 مخصصة، يمكنك إنشاء ملف `404.astro` أو `404.md` في `src/pages`.

سيؤدي هذا إلى بناء صفحة `404.html`. سيجدها معظم [موفري النشر (Deploy Services)](/ar/guides/deploy/) وسيستخدمها.

## صفحة خطأ 500 مخصصة

لصفحة خطأ 500 مخصصة لعرضها للصفحات التي [يتم تقديمها عند الطلب (On-demand Rendering)](/ar/guides/on-demand-rendering/)، أنشئ الملف `src/pages/500.astro`. هذه الصفحة المخصصة غير متاحة للصفحات التي يتم تقديمها مسبقًا (Prerendered).

إذا حدث خطأ أثناء تقديم هذه الصفحة، فسيتم عرض صفحة الخطأ الافتراضية 500 الخاصة بمضيفك لزائرك.

<p><Since v="4.10.3" /></p>

أثناء التطوير، إذا كان لديك ملف `500.astro`، فسيتم تسجيل الخطأ الذي تم طرحه أثناء وقت التشغيل في الطرفية (Terminal) الخاصة بك، بدلاً من عرضه في نافذة الأخطاء (Error Overlay).

### `error`

<p><Since v="4.11.0" /></p>

`src/pages/500.astro` هي صفحة خاصة يتم تمرير خاصية `error` تلقائيًا لها لأي خطأ يتم طرحه أثناء التقديم. هذا يسمح لك باستخدام تفاصيل الخطأ (مثل خطأ من صفحة، من middleware، إلخ) لعرض المعلومات لزائرك.

يمكن أن يكون نوع بيانات خاصية `error` أي شيء، مما قد يؤثر على كيفية كتابة النوع (Typing) أو استخدام القيمة في الكود الخاص بك:

```astro title="src/pages/500.astro"
---
interface Props {
  error: unknown;
}

const { error } = Astro.props;
---
<div>{error instanceof Error ? error.message : "خطأ غير معروف"}</div>
```

لتجنب تسريب معلومات حساسة عند عرض محتوى من خاصية `error`، فكر في تقييم الخطأ أولاً، وإرجاع محتوى مناسب بناءً على الخطأ الذي تم طرحه. على سبيل المثال، يجب عليك تجنب عرض الـ (Stack Trace) للخطأ لأنه يحتوي على معلومات حول كيفية هيكلة الكود الخاص بك على الخادم.

## الصفحات الجزئية

<p><Since v="3.4.0" /></p>

:::caution
الصفحات الجزئية مخصصة للاستخدام جنبًا إلى جنب مع مكتبة واجهة أمامية (Front-end)، مثل [htmx](https://htmx.org/) أو [Unpoly](https://unpoly.com/). يمكنك أيضًا استخدامها إذا كنت مرتاحًا لكتابة JavaScript منخفض المستوى للواجهة الأمامية. لهذا السبب، فهي ميزة متقدمة.

بالإضافة إلى ذلك، لا ينبغي استخدام الجزئيات إذا كان المكون يحتوي على أنماط (Styles) أو نصوص برمجية (Scripts) محددة النطاق (Scoped)، حيث سيتم إزالة هذه العناصر من ناتج HTML. إذا كنت بحاجة إلى أنماط محددة النطاق، فمن الأفضل استخدام صفحات عادية غير جزئية مع مكتبة واجهة أمامية تعرف كيفية دمج المحتويات في head.
:::

الجزئيات (Partials) هي مكونات صفحات موجودة داخل `src/pages/` لا يُقصد بها أن تُعرض كصفحات كاملة.

مثل المكونات الموجودة خارج هذا المجلد، لا تتضمن هذه الملفات تلقائيًا تعريف `<!DOCTYPE html>`، ولا أي محتوى `<head>` مثل الأنماط أو النصوص البرمجية محددة النطاق.

ومع ذلك، نظرًا لأنها موجودة في الدليل الخاص `src/pages/`، فإن HTML الذي تم إنشاؤه يكون متاحًا عند عنوان URL يتوافق مع مسار ملفه. هذا يسمح لمكتبة تقديم (Rendering Library) (مثل [htmx](https://htmx.org/)، [Stimulus](https://stimulus.hotwired.dev/)، [jQuery](https://jquery.com/)) بالوصول إليها على العميل (Client) وتحميل أقسام HTML ديناميكيًا على صفحة دون تحديث المتصفح أو التنقل بين الصفحات.

توفر الجزئيات، عند دمجها مع مكتبة تقديم، بديلاً [لجزر أسترو (Astro Islands)](/ar/concepts/islands/) و [علامات `<script>`](/ar/guides/client-side-scripts/) لبناء محتوى ديناميكي في أسترو.

ملفات الصفحات التي يمكنها تصدير قيمة لـ [`partial`](/ar/reference/routing-reference/#partial) (مثل `.astro` و `.mdx`، ولكن ليس `.md`) يمكن وضعها كجزئيات.

```astro title="src/pages/partial.astro" ins={2}
---
export const partial = true;
---
<li>أنا جزء جزئي!</li>
```

### الاستخدام مع مكتبة

تُستخدم الجزئيات لتحديث قسم من الصفحة ديناميكيًا باستخدام مكتبة مثل [htmx](https://htmx.org/).

يظهر المثال التالي سمة `hx-post` مضبوطة على عنوان URL الجزئي. سيتم استخدام المحتوى من صفحة الجزئي لتحديث عنصر HTML المستهدف على هذه الصفحة.

```astro title="src/pages/index.astro" 'hx-post="/partials/clicked/"'
<html lang="ar" dir="rtl">
  <head>
    <title>صفحتي</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
  <body>
    <section>
      <div id="parent-div">الهدف هنا</div>
    
      <button hx-post="/partials/clicked/"
        hx-trigger="click"
        hx-target="#parent-div"
        hx-swap="innerHTML"
      >
        انقر هنا!
      </button>
    </section>
  </body>
</html>
```

يجب أن يوجد الجزئي `.astro` في مسار الملف المقابل، ويشمل تصديرًا يحدد الصفحة كجزئي:

```astro title="src/pages/partials/clicked.astro" {2}
---
export const partial = true;
---
<div>تم النقر علي!</div>
```

راجع [وثائق htmx](https://htmx.org/docs/) لمزيد من التفاصيل حول استخدام htmx.
